# Adafruit IO MQTT API

[MQTT](http://mqtt.org/), or message queue telemetry transport, is a protocol for device communication that Adafruit IO supports. Using a MQTT library or client you can publish and subscribe to a feed to send and receive feed data.

If you aren't familiar with MQTT check out this [introduction from the HiveMQ blog](http://www.hivemq.com/mqtt-essentials-part-1-introducing-mqtt/).
All of the subsequent posts in the [MQTT essentials series](http://www.hivemq.com/mqtt-essentials-wrap-up/) are great and worth reading too.


## Client Libraries


To use the MQTT API that Adafruit IO exposes you'll need a MQTT client library.  For Python, Ruby, and Arduino you can use Adafruit's
IO libraries as they include support for MQTT. For other languages or platforms look for a MQTT library that ideally supports the MQTT 3.1.1 protocol.

* **Arduino**: [Adafruit MQTT](https://github.com/adafruit/Adafruit_MQTT_Library)

* **Python**: [Adafruit IO Python](https://github.com/adafruit/Adafruit_IO_Python) includes an MQTT Client.

* **CircuitPython**: [Adafruit IO CircuitPython](https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/) includes a MQTT Client class, `IO_MQTT`.

* **MicroPython**: MicroPython devices can connect to Adafruit IO using [uMQTT](https://github.com/micropython/micropython-lib/tree/master/umqtt.simple)

* **Ruby**: [Adafruit IO Ruby](https://github.com/adafruit/io-client-ruby) includes an MQTT client.

## MQTT Connection Details

We *strongly* recommend connecting using SSL (Port 8883) if your client allows it.  Port 443 is for MQTT-over-Websockets
clients which generally run in browsers, like Eclipse Paho, HiveMQ Websockets, or MQTTJS.

|                      |                           |
|----------------------|---------------------------|
| **Host**             | io.adafruit.com           |
| **Secure (SSL) Port**| 8883                      |
| **Insecure Port**    | 1883                      |
| **MQTT over Websocket| 443                       |
| **Username**         | Your Adafruit IO Username |
| **Password**         | Your Adafruit IO Key      |

_Need to manually set a Client ID for your MQTT client?_ Use a unique value such as a [random GUID](https://www.guidgenerator.com/online-guid-generator.aspx). Whenever possible, leave the client ID field blank.

<aside class="notice">
Connecting to Adafruit IO via MQTT and reusing the client ID of an existing connection will result in <strong>immediate disconnection</strong> of the other MQTT client. The MQTT specification requires that "each client connecting to the server has a unique ClientId." <a href="http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/csprd02/mqtt-v3.1.1-csprd02.html#_Toc385349767">link</a>
</aside>

We do not currently limit the number of clients that can connect to Adafruit IO, but we do limit the rate at which connections may be attempted to 20 per minute. Exceeding the connection attempt rate limit will result in a temporary ban.
